home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / dbopen.0 < prev    next >
Text File  |  1996-09-02  |  16KB  |  397 lines
  1.  
  2.  
  3.  
  4. DBOPEN(3)                                               DBOPEN(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        dbopen - database access methods
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  12.        ##iinncclluuddee <<lliimmiittss..hh>>
  13.        ##iinncclluuddee <<ddbb..hh>>
  14.  
  15.        DDBB **
  16.        ddbbooppeenn((ccoonnsstt cchhaarr **ffiillee,, iinntt ffllaaggss,, iinntt mmooddee,, DDBBTTYYPPEE ttyyppee,,
  17.             ccoonnsstt vvooiidd **ooppeenniinnffoo));;
  18.  
  19. DDEESSCCRRIIPPTTIIOONN
  20.        _D_b_o_p_e_n  is  the  library interface to database files.  The
  21.        supported file formats are btree,  hashed  and  UNIX  file
  22.        oriented.   The  btree  format  is  a  representation of a
  23.        sorted, balanced tree structure.  The hashed format is  an
  24.        extensible,  dynamic hashing scheme.  The flat-file format
  25.        is a byte  stream  file  with  fixed  or  variable  length
  26.        records.  The formats and file format specific information
  27.        are described in detail in their respective  manual  pages
  28.        _b_t_r_e_e(3), _h_a_s_h(3) and _r_e_c_n_o(3).
  29.  
  30.        Dbopen opens _f_i_l_e for reading and/or writing.  Files never
  31.        intended to be preserved on disk may be created by setting
  32.        the file parameter to NULL.
  33.  
  34.        The  _f_l_a_g_s  and  _m_o_d_e  _a_r_g_u_m_e_n_t_s  are  as specified to the
  35.        _o_p_e_n(2)  routine,  however,  only  the  O_CREAT,   O_EXCL,
  36.        O_EXLOCK,   O_NONBLOCK,  O_RDONLY,  O_RDWR,  O_SHLOCK  and
  37.        O_TRUNC flags are meaningful.  (Note, opening  a  database
  38.        file O_WRONLY is not possible.)
  39.  
  40.        The  _t_y_p_e  argument  is  of type DBTYPE (as defined in the
  41.        <db.h> include file) and may be set to  DB_BTREE,  DB_HASH
  42.        or DB_RECNO.
  43.  
  44.        The  _o_p_e_n_i_n_f_o  argument  is  a pointer to an access method
  45.        specific structure described in the access method's manual
  46.        page.   If  _o_p_e_n_i_n_f_o  is NULL, each access method will use
  47.        defaults appropriate for the system and the access method.
  48.  
  49.        _D_b_o_p_e_n  returns a pointer to a DB structure on success and
  50.        NULL on error.  The DB structure is defined in the  <db.h>
  51.        include file, and contains at least the following fields:
  52.  
  53.        typedef struct {
  54.               DBTYPE type;
  55.               int (*close)(const DB *db);
  56.               int (*del)(const DB *db, const DBT *key, u_int flags);
  57.               int (*fd)(const DB *db);
  58.               int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
  59.               int (*put)(const DB *db, DBT *key, const DBT *data,
  60.                    u_int flags);
  61.  
  62.  
  63.  
  64.                          January 2, 1994                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DBOPEN(3)                                               DBOPEN(3)
  71.  
  72.  
  73.               int (*sync)(const DB *db, u_int flags);
  74.               int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
  75.        } DB;
  76.  
  77.        These elements describe a database type and a set of func-
  78.        tions performing various actions.  These functions take  a
  79.        pointer  to  a  structure as returned by _d_b_o_p_e_n, and some-
  80.        times one or more pointers to key/data  structures  and  a
  81.        flag value.
  82.  
  83.        type   The  type of the underlying access method (and file
  84.               format).
  85.  
  86.        close  A pointer to a routine to flush any cached informa-
  87.               tion  to  disk,  free  any allocated resources, and
  88.               close the underlying file(s).  Since key/data pairs
  89.               may  be  cached in memory, failing to sync the file
  90.               with a _c_l_o_s_e or _s_y_n_c function may result in  incon-
  91.               sistent or lost information.  _C_l_o_s_e routines return
  92.               -1 on error (setting _e_r_r_n_o) and 0 on success.
  93.  
  94.        del    A pointer to a routine  to  remove  key/data  pairs
  95.               from the database.
  96.  
  97.               The  parameter  _f_l_a_g  may  be  set to the following
  98.               value:
  99.  
  100.               R_CURSOR
  101.                      Delete the record referenced by the  cursor.
  102.                      The  cursor  must  have previously been ini-
  103.                      tialized.
  104.  
  105.               _D_e_l_e_t_e routines return -1 on error (setting _e_r_r_n_o),
  106.               0 on success, and 1 if the specified _k_e_y was not in
  107.               the file.
  108.  
  109.        fd     A  pointer  to  a  routine  which  returns  a  file
  110.               descriptor   representative   of   the   underlying
  111.               database.  A file descriptor referencing  the  same
  112.               file  will  be returned to all processes which call
  113.               _d_b_o_p_e_n with the same _f_i_l_e name.  This file descrip-
  114.               tor  may  be  safely  used  as  an  argument to the
  115.               _f_c_n_t_l(2) and _f_l_o_c_k(2) locking functions.  The  file
  116.               descriptor  is  not necessarily associated with any
  117.               of the underlying files used by the access  method.
  118.               No  file  descriptor  is  available  for  in memory
  119.               databases.  _F_d routines return -1 on error (setting
  120.               _e_r_r_n_o), and the file descriptor on success.
  121.  
  122.        get    A  pointer  to a routine which is the interface for
  123.               keyed retrieval from the database.  The address and
  124.               length  of  the  data associated with the specified
  125.               _k_e_y are returned in  the  structure  referenced  by
  126.               _d_a_t_a.   _G_e_t  routines  return  -1 on error (setting
  127.  
  128.  
  129.  
  130.                          January 2, 1994                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DBOPEN(3)                                               DBOPEN(3)
  137.  
  138.  
  139.               _e_r_r_n_o), 0 on success, and 1 if the _k_e_y was  not  in
  140.               the file.
  141.  
  142.        put    A  pointer  to a routine to store key/data pairs in
  143.               the database.
  144.  
  145.               The parameter _f_l_a_g may be set to one of the follow-
  146.               ing values:
  147.  
  148.               R_CURSOR
  149.                      Replace  the key/data pair referenced by the
  150.                      cursor.  The  cursor  must  have  previously
  151.                      been initialized.
  152.  
  153.               R_IAFTER
  154.                      Append  the  data immediately after the data
  155.                      referenced by _k_e_y, creating a  new  key/data
  156.                      pair.   The  record  number  of the appended
  157.                      key/data pair is returned in the _k_e_y  struc-
  158.                      ture.   (Applicable  only  to  the  DB_RECNO
  159.                      access method.)
  160.  
  161.               R_IBEFORE
  162.                      Insert the data immediately before the  data
  163.                      referenced  by  _k_e_y, creating a new key/data
  164.                      pair.  The record  number  of  the  inserted
  165.                      key/data  pair is returned in the _k_e_y struc-
  166.                      ture.   (Applicable  only  to  the  DB_RECNO
  167.                      access method.)
  168.  
  169.               R_NOOVERWRITE
  170.                      Enter  the new key/data pair only if the key
  171.                      does not previously exist.
  172.  
  173.               R_SETCURSOR
  174.                      Store the key/data pair, setting or initial-
  175.                      izing  the  position of the cursor to refer-
  176.                      ence it.  (Applicable only to  the  DB_BTREE
  177.                      and DB_RECNO access methods.)
  178.  
  179.               R_SETCURSOR  is available only for the DB_BTREE and
  180.               DB_RECNO access methods because it implies that the
  181.               keys  have an inherent order which does not change.
  182.  
  183.               R_IAFTER and R_IBEFORE are available only  for  the
  184.               DB_RECNO access method because they each imply that
  185.               the access method is able to create new keys.  This
  186.               is  only  true if the keys are ordered and indepen-
  187.               dent, record numbers for example.
  188.  
  189.               The default behavior of  the  _p_u_t  routines  is  to
  190.               enter  the  new key/data pair, replacing any previ-
  191.               ously existing key.
  192.  
  193.  
  194.  
  195.  
  196.                          January 2, 1994                        3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DBOPEN(3)                                               DBOPEN(3)
  203.  
  204.  
  205.               _P_u_t routines return -1 on error (setting _e_r_r_n_o),  0
  206.               on success, and 1 if the R_NOOVERWRITE _f_l_a_g was set
  207.               and the key already exists in the file.
  208.  
  209.        seq    A pointer to a routine which is the  interface  for
  210.               sequential   retrieval   from  the  database.   The
  211.               address and length of the key are returned  in  the
  212.               structure  referenced  by  _k_e_y, and the address and
  213.               length of the data are returned  in  the  structure
  214.               referenced by _d_a_t_a.
  215.  
  216.               Sequential key/data pair retrieval may begin at any
  217.               time, and the position of  the  ``cursor''  is  not
  218.               affected  by  calls  to  the _d_e_l, _g_e_t, _p_u_t, or _s_y_n_c
  219.               routines.  Modifications to the database  during  a
  220.               sequential scan will be reflected in the scan, i.e.
  221.               records inserted behind  the  cursor  will  not  be
  222.               returned  while  records  inserted  in front of the
  223.               cursor will be returned.
  224.  
  225.               The flag value mmuusstt be set to one of the  following
  226.               values:
  227.  
  228.               R_CURSOR
  229.                      The  data  associated with the specified key
  230.                      is returned.  This differs from the _g_e_t rou-
  231.                      tines  in  that  it  sets or initializes the
  232.                      cursor to the location of the key  as  well.
  233.                      (Note,  for  the DB_BTREE access method, the
  234.                      returned key is  not  necessarily  an  exact
  235.                      match  for  the specified key.  The returned
  236.                      key is the  smallest  key  greater  than  or
  237.                      equal  to the specified key, permitting par-
  238.                      tial key matches and range searches.)
  239.  
  240.               R_FIRST
  241.                      The first key/data pair of the  database  is
  242.                      returned,  and the cursor is set or initial-
  243.                      ized to reference it.
  244.  
  245.               R_LAST The last key/data pair of  the  database  is
  246.                      returned,  and the cursor is set or initial-
  247.                      ized to reference it.  (Applicable  only  to
  248.                      the DB_BTREE and DB_RECNO access methods.)
  249.  
  250.               R_NEXT Retrieve the key/data pair immediately after
  251.                      the cursor.  If the cursor is not  yet  set,
  252.                      this is the same as the R_FIRST flag.
  253.  
  254.               R_PREV Retrieve   the   key/data  pair  immediately
  255.                      before the cursor.  If the cursor is not yet
  256.                      set,  this  is  the same as the R_LAST flag.
  257.                      (Applicable  only  to   the   DB_BTREE   and
  258.                      DB_RECNO access methods.)
  259.  
  260.  
  261.  
  262.                          January 2, 1994                        4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. DBOPEN(3)                                               DBOPEN(3)
  269.  
  270.  
  271.               R_LAST  and  R_PREV  are  available  only  for  the
  272.               DB_BTREE and DB_RECNO access methods  because  they
  273.               each  imply  that  the  keys have an inherent order
  274.               which does not change.
  275.  
  276.               _S_e_q routines return -1 on error (setting _e_r_r_n_o),  0
  277.               on  success  and  1  if there are no key/data pairs
  278.               less than or greater than the specified or  current
  279.               key.   If the DB_RECNO access method is being used,
  280.               and if the database file  is  a  character  special
  281.               file  and  no complete key/data pairs are currently
  282.               available, the _s_e_q routines return 2.
  283.  
  284.        sync   A pointer to a routine to flush any cached informa-
  285.               tion  to  disk.  If the database is in memory only,
  286.               the _s_y_n_c routine has no effect and will always suc-
  287.               ceed.
  288.  
  289.               The flag value may be set to the following value:
  290.  
  291.               R_RECNOSYNC
  292.                      If the DB_RECNO access method is being used,
  293.                      this flag causes the sync routine  to  apply
  294.                      to  the btree file which underlies the recno
  295.                      file, not the recno file itself.   (See  the
  296.                      _b_f_n_a_m_e field of the _r_e_c_n_o(3) manual page for
  297.                      more information.)
  298.  
  299.               _S_y_n_c routines return -1 on  error  (setting  _e_r_r_n_o)
  300.               and 0 on success.
  301.  
  302. KKEEYY//DDAATTAA PPAAIIRRSS
  303.        Access to all file types is based on key/data pairs.  Both
  304.        keys and data are represented by the following data struc-
  305.        ture:
  306.  
  307.        typedef struct {
  308.               void *data;
  309.               size_t size;
  310.        } DBT;
  311.  
  312.        The elements of the DBT structure are defined as follows:
  313.  
  314.        data   A pointer to a byte string.
  315.  
  316.        size   The length of the byte string.
  317.  
  318.        Key  and data byte strings may reference strings of essen-
  319.        tially unlimited length although any two of them must  fit
  320.        into  available  memory  at  the  same time.  It should be
  321.        noted that the access methods provide no guarantees  about
  322.        byte string alignment.
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                          January 2, 1994                        5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. DBOPEN(3)                                               DBOPEN(3)
  335.  
  336.  
  337. EERRRROORRSS
  338.        The  _d_b_o_p_e_n  routine may fail and set _e_r_r_n_o for any of the
  339.        errors specified for the library routines _o_p_e_n(2) and _m_a_l_-
  340.        _l_o_c(3) or the following:
  341.  
  342.        [EFTYPE]
  343.               A file is incorrectly formatted.
  344.  
  345.        [EINVAL]
  346.               A  parameter has been specified (hash function, pad
  347.               byte etc.) that is incompatible  with  the  current
  348.               file  specification  or which is not meaningful for
  349.               the function (for example, use of the cursor  with-
  350.               out  prior  initialization)  or there is a mismatch
  351.               between the version number of file  and  the  soft-
  352.               ware.
  353.  
  354.        The  _c_l_o_s_e  routines may fail and set _e_r_r_n_o for any of the
  355.        errors  specified  for  the  library  routines   _c_l_o_s_e(2),
  356.        _r_e_a_d(2), _w_r_i_t_e(2), _f_r_e_e(3), or _f_s_y_n_c(2).
  357.  
  358.        The  _d_e_l, _g_e_t, _p_u_t and _s_e_q routines may fail and set _e_r_r_n_o
  359.        for any of the errors specified for the  library  routines
  360.        _r_e_a_d(2), _w_r_i_t_e(2), _f_r_e_e(3) or _m_a_l_l_o_c(3).
  361.  
  362.        The  _f_d  routines will fail and set _e_r_r_n_o to ENOENT for in
  363.        memory databases.
  364.  
  365.        The _s_y_n_c routines may fail and set _e_r_r_n_o for  any  of  the
  366.        errors specified for the library routine _f_s_y_n_c(2).
  367.  
  368. SSEEEE AALLSSOO
  369.        _b_t_r_e_e(3), _h_a_s_h(3), _m_p_o_o_l(3), _r_e_c_n_o(3)
  370.  
  371.        _L_I_B_T_P_:  _P_o_r_t_a_b_l_e_,  _M_o_d_u_l_a_r  _T_r_a_n_s_a_c_t_i_o_n_s  _f_o_r  _U_N_I_X, Margo
  372.        Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
  373.  
  374. BBUUGGSS
  375.        The typedef DBT is a mnemonic for ``data base thang'', and
  376.        was  used  because  noone could think of a reasonable name
  377.        that wasn't already used.
  378.  
  379.        The file descriptor interface  is  a  kluge  and  will  be
  380.        deleted in a future version of the interface.
  381.  
  382.        None  of the access methods provide any form of concurrent
  383.        access, locking, or transactions.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                          January 2, 1994                        6
  395.  
  396.  
  397.